nwn2fandomcom-20200214-history
GUI
GUI (or UI) is short for Graphical User Interface (or User Interface). It is the main interaction point between a player and the game. It consists of all of the buttons, panels and menus in the game. The NWN2 UI is fully customizable and script-able. Panel backgrounds, size, location, color and layout can all be modified. The UI is made up of a collection of UI Scenes, which is essentially a hierarchy of panels and elements, formatted and styled using XML. The UI is defined by the ingamegui.ini file which lists all the UI Scenes with their associated .xml files. Each of these files describes a UI Scene such as the HotBar or the Character Sheet. The UI Scenes contain references to .tga files, .dds files and both internal (hard-coded) and scripted function calls. The XML files define the UI elements such as size and position and more advanced settings and scripts to some extent. e.g: Defines a new UI Scene which can be referenced to by script under the name "SCREEN_CHARACTER" (in this case, the character statistics window). Targa (.tga) files are images files which can be edited in most image-editing programs. The targa files consists of one layer and 4 channels, 3 channels for RGB and 1 channel for Alpha. When drawing in an alpha channel, black represents 100% transparency, white 0% transparency, some gray colors between are half transparent. When saving .tga files, do not save with the original name, use a new name and remember to change the association in the correct XML file too. Saving with the original name will make NWN2 load the original images, even if they have been replaced in the UI folder. When doing UI changes, the files have to be placed in My Documents/Neverwinter Nights 2/ folder, and it's a good idea to save the original files in the /program directory. Changes can be put in My Documents/Neverwinter Nights/UI/default, or in My Documents/Neverwinter Nights/override. UI Elements The following table lists the available elements within the NWN2 GUI. HotBar Tutorial This is a short tutorial on how to modify the Hot-Bar (aka Quick Slot) by increasing its length and the number of visible slots and reducing its overall size. The XML file that defines the layout of the Hot-Bar is called hotbar.xml and can be found in your Neverwinter Nights 2 directory within the UI folders default scheme. For example: C:Program Files\Atari\Neverwinter Nights 2\ui\default\hotbar.xml With NWN2, custom content can be added to the My Documents directory, ..\My Documents\Neverwinter Nights 2\, this is the directory under which the new modded UI should go. For example: C:\Documents and Settings\user_name\My Documents\Neverwinter Nights 2\ui\hotbar.xml This will override the standard hot-bar. Idle Expire & Live Editing The first useful step when modding the UI is make sure that the UIScene has the idleexpiretime field set (about 0.5f or 1.0f), this will unload the UIScene from memory after closing the scene. This is advantageous in that changes to the XML layout can be seen immediately, while NWN2 is running, without requiring an application restart. Simply closing the Window/Scene within NWN2 and waiting for the expire time before re-opening it again will refresh the scene layout, revealing any changes. Usually, the UIScene in hotbar.xml does not have idleexpiretime so it should be added the start of NWN2. An easy way to force a refresh of the hotbar in-game is to go to the Menu->Game Options->Interface and unclick Show Horizontal Hotbar 1 (Default Hotbar) then Apply Changes then reclick the hotbar on, and reapply the changes. The standard Hot-Bar The standard NWN2 hotbar is made up of a collection of UI elements. Main UI elements: # CurrentHotbar UIText element # GridUp1 UIButton element # HOTBAR_TEXT UIText arranged to a UIGrid # HOTBAR_TEXT UIText arranged to a UIGrid # UIHotbarButton element arranged to the grid # UIHotbarButton element arranged to the grid # Background texture UIICon parented to the hotbar scene Modifying the Hot-bar to contain 20 slots In order to modify the hot-bar, a a few things need changing: # The number of slots # The width of the hot-bar field First, the number of colums. Open up hotbar.xml with a .xml editor, such as notepad++. Look through the .xml file for element UIGrid: In order to extend the number of slots, simply change the value of columns to 20. The resulting line should look like: Now a bit of simple math to figure out how wide the hotbar field should be. Notice the second element, UIHotbarButton contains a height and width for each hotbar slot. It is square, but there is only a concern with width. The actual width might vary (maybe with screen resolution?), in this example, the width is 40. There is also a small padding on each button, xPadding, which here is 2. The width of the field is contained in the top level element, UIScene: To extend the width of the field, simply + the number of slots added * (the width of one slot + the padding + 1 (not sure why, but needed to make spacing right)) to the existing width. In this example, there is an existing width of 560, added 8 slots, each slot has a width of 40, and a padding of 2 so: 560 + (8 * (40 + 2 + 1)) = 904 Therefore, the modified element should be: Additional changes are required to make the text elements align with the bar's background texture. The fully modified XML file can be downloaded and contains comments explaining the function and layout (see available files). The finished and extended Hotbar looks a bit like this: Available Files hotbar.xmlhttp://www.aovc12.dsl.pipex.com/Scripts/UI/hotbar.xml dead Input Box Tutorial This tutorial guides through the creation of a custom user interface screen. The screen is responsible for allowing the user to change their characters name. This is an illustrative example but could be easily extended for a variety of other purposes. A sample module is included that allows to ask a gnomish 'name changer' to change the name, this just shows one use of such a script and screen. Scripting GUI scripting allows to dynamically update the contents of scenes, and have scripted responses to buttons pressed. Text fields can also be used to have the user enter information which the script can process, e.g. for changing a character's name. The Bioware forums contain a thread on GUI scripting, containing pre release information by Rich Taylor (Obsidian Lead Developer) and information figured out by the community. The Grinning Fool has extracted a list of all tags, attributes, events and functions which can be found here. For a practical example of using server side scripting to update elements in the UI, have a look at Cyric's compact character sheet with alignment values: http://nwvault.ign.com/View.php?view=NWN2UI.Detail&id=17. Important Points For a GUI to be called from a script it must be declared in the client side ingamegui.ini file in the MandatoryGUI section. This can not be acheived with an override file. (QK's note: since patch 1.06, there's no need of using a custom .ini for UI works, so this last phrase can be avoided) In the SceneUI Tag the attribute "scriptloadable" has to be set to "true" for manipulation of local GUI vars or text objects via script, even if the xml would not be loaded via script. GUI callbacks can be put on UIObjects that fire off scripts on the server. What this means is a button in the GUI that fires a script every time it is clicked. Or it could made so that every time a certain window is brought up, a script is executed on the server. Scripts can only be executed if they are named: "gui_*". If they do not start with gui_ in the name, the server will reject the request to fire the script. This will help prevent clients from firing off whatever script they want to just by knowing the name of it. It will be up to the script writers themselves to make sure that the gui_ scripts are written in such a way that clients can't abuse them by calling them whenever they want. A few script functions exist to give some basic control over the GUI: *Pop up a GUI Scene from nwn script DisplayGuiScreen( oPlayer, sScreenID, bModal ); *Display a message box. Allows to define the message text, the text for the 'okay' button, the text for the 'cancel' button, whether or not cancel is displayed, and the scripts to execute if the user clicks okay or cancel. Scripts must again be named with "gui_" DisplayMessageBox( oPlayer, nMessageStrRef, sMessage, sOkCallback, sCancelCB, bShowCancel, sScreenID, nOkStrRef, sOkString, nCancelStrRef, sCancelString ); *Determine if a specific object on a UI on that client is visible or not. This gives script some limited control on altering the appearance of a GUI window by toggling things visible or invisible. This has the same restrictions as 'DisplayGUIScreen', in that there are some restrictions on which GUIs can be affected with this function. SetGUIObjectHidden( oPlayer, sScreenID, sUIObjectName, bHidden ); *Close the screen on the client. Again, there are restrictions on which GUIs can be affected with this. CloseGUIScreen( oPlayer, sScreenID ); Using GUI variables This function is a bit more advanced in its use. But briefly, there is a set of local variables on every GUI window. The GUI layer interacts with these variables at times. And with this script function, scripts can as well. This script function can be used in combination with certain GUI callback functions. For example, there is a GUI callback for OnUpdate that will display the contents of a local variable. Strings can appear in a custom window (or similar) in the player's GUI. Or there is a GUI callback that will set a UI Object as 'disabled' if a local variable contains a certain value. So a certain button can be disabled on the custom screen if the local GUI variable on that screen has a certain value, and so forth. SetLocalGUIVariable( oPlayer, sScreenID, nVarIndex, sVarValue ); From the client/UI/xml *Set a local (UI) variable. UIObject_Misc_SetLocalVarString(local:1) *Use a local variable. OnUpdate='UIText_OnUpdate_DisplayLocalVar(local:1) *Send a variable to the client/UI UIObject_Misc_ExecuteServerScript("my_script_name",local:1) From the server/script *Set a variable from the client/UI. In a script called by the UI (name starting with gui_), give the main function some parameters: void main(string variable_name) These parameters will be set by the UI call UIObject_Misc_ExecuteServerScript *Set a local variable & send to client/UI SetLocalGUIVariable(oPC,"SCREEN_VN_ITEM_APPEARANCE_CHANGER",2,"Make changes to the item"); *Use a local variable. Same as using a script variable once it has been received in the main function's parameters. *Charlie's Item Appearance Changer makes extensive use of variables and might be useful to look at. External Links *Grinning Fool's NWN2 UI Reference *Rich Taylor's UI Blog *BetterThanLife's UI Tutorial *Lance Botelle's NWN2 XML & GUI Coding For Beginners Category:GUI Category:Custom content Category:Tutorials